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Overview 


Right now, a wide variety of technologies exist to provide on-disk data encryption on Linux 
distributions. These include block level solutions (e.g. dm-crypt), stacked filesystem solutions 
(e.g. eCryptfs), and native filesystem solutions (e.g. native ext4 encryption). While good 
userspace utilities exist for block level solutions (cryptsetup) and stacked filesystem solutions 
(ecryptfs-utils), no good single userspace utility exists for native filesystem solutions. 


Right now the process for setting up native filesystem encryption is quite fragmented. Ext4 
native encryption has a userspace tool (e4crypt), but it is lacking some key features (see the 
e4crypt section below). F2FS lacks a userspace utility, meaning that users have to use the raw 
fs/crypto kernel interface to set up encryption. With plans for native filesystem encryption for 
ubifs, xfs and btrfs in the works, we want to avoid having a separate userspace tool for each 
filesystem. 


Having multiple native filesystem encryption utilities means that each solution has to implement 
key derivation, key wrapping, and metadata management. These tasks have no need to be tied 
to the underlying filesystem. Also, by having them implemented in several locations, it makes it 
hard to change or improve them as better algorithms come along or security vulnerabilities are 
found. 


Goals 


fscrypt’s goal is to provide a unified simple setup and management for native filesystem 
encryption technologies (ext4, ubifs, f2fs, etc...) that use the fs/crypto kernel interface. 
Regardless of the underlying filesystem being used, the setup should be as similar as possible. 


fscrypt manages the following components: 
e User Experience (via a command line tool) 
Encryption configurations/modes 
Key Derivation Algorithm 
Key Wrapping 
Cryptographic Metadata content and format 


fscrypt also allows for reasonable defaults to be passed to each of the underlying filesystems, 
making encryption setup secure and simple by default. We also allow for more fine-tuned control 
of encryption options if there are backwards compatibility concerns. 


Having fscrypt achieves three key things. First, by making encryption easier to set up, we make 
it easier for distributions to integrate with filesystem encryption, increasing the prevalence of 
encryption. Second, by managing many previously manual tasks, we make it harder to set up 
encryption in an insecure manner. Finally, by having fscrypt work across filesystems, we make it 
easier for new filesystem encryption technologies to take advantage of fscrypt. 


Example Use Cases 
When considering our goals for fscrypt, it is important to keep in mind some common use cases 
for filesystem encryption. Our goal is for fscrypt to support the following use cases: 

e Auser has a directory on their system (e.g. ~/bitcoin) that they wish to encrypt with a 
custom password. The data can be accessed if and only if a user knows the custom 
password. This is essentially the current functionality of e4crypt. Also, they can change 
the password for this directory (not supported by e4crypt). 

e Auser has one directory (e.g. their home directory) or several directories (e.g. 
~/Private, ~/Mail, and ~/Pictures) on their system that they wish to be encrypted 
with their login credentials and unlocked automatically when they login. This will keep 
working even if the login password is changed. 

e Auser has a directory on their system (e.g. /var/shared) that they wish to be encrypted 
and accessible to two different users automatically on login. 

e Auser has some number of directories on their system (e.g. /etc, /var, and /log) that 
they wish to encrypt with a secret sealed by a TPM or other hardware source. 

e Auser has a directory on some removable media (e.g., mounted at 
/media/usb/Private) that they wish to encrypt with a custom password, and they want 
to be able to change this password. 

e Auser has a directory on some removable media (e.g., mounted at 
/media/usb/Private) that they wish to encrypt with a custom password, but also be 
able to access with their login password. This means that if the USB is plugged into 
another system, a custom password is required. However, if it is plugged into the user’s 
main system, the directory is unlocked at login. Furthermore, if the user is already logged 
in and the USB is then plugged in, no additional action is needed; the files are available 
and unlocked. 

e Fora given encrypted directory, the user can ask for a recovery token for that directory. 
Any point in the future, this recovery token is enough to unlock the contents of the 
directory. It doesn’t matter if more files have been written to this directory, or the method 
of protecting the directory has changed. 


Threat Model 


For the most part, fscrypt needs to protect against the same kind of threats that native 
filesystem encryption does. With the addition of metadata, we also need to make sure that the 
access controls still work effectively. 


Our first threat is the classic threat when dealing with filesystem encryption: an attacker who 
gains access to the filesystem media when the system is off. In this case, if a directory hierarchy 
is protected with a secret (or several secrets) then the data in that directory hierarchy (filenames 
and file contents) should remain confidential unless the attacker has access to the secret. 


The addition of metadata means we now have to be concerned about a user corrupting another 
user’s metadata. Consider the case where Alice sets up an encrypted directory, and Bob 


deletes Alice's metadata. Bob has effectively deleted Alice’s directory by making it impossible 
for Alice to access the data in that directory. If Bob didn’t have write permission to Alice’s 
directory, this effectively bypasses access controls. Thus, we need to make sure users cannot 
delete metadata without proper permission. 


Importantly, there are two threats that are not in the threat model for fscrypt. First, other than in 
the above case regarding metadata, we do not deal with preventing other users from 
reading/writing/deleting data to which they do not have permissions. This is the job of standard 
unix file permissions. Filesystem encryption is not a replacement for unix file permissions. 
You need both to get effective confidentiality. 


Second, we do not prevent an attacker who has physical access from deleting or modifying the 
metadata. This is because countering that threat gives us no additional security value (without 
hardware support for authenticity). An attacker with physical access can just delete all of your 
files, or modify the kernel to intercept your keys. The real solution to these sorts of attacks is 
getting some form of authenticity on either the filesystem or disk media. However, that is well 
outside the scope of fscrypt. Here is a discussion of how such authenticity checks would 
integrate with fscrypt. 


Existing Encryption Tools 


cryptsetup 

httos://wiki.archlinux.org/index.php/Dm-crypt/Device_encryption 

Cryptsetup is the main command line tool for setting up dm-crypt based encryption. It supports 
both dm-crypt with a LUKS header, raw dm-crypt, and many other block level encryption 
solutions. In the case of raw dm-crypt, all that is needed is a raw master key that cannot be 
changed. For dm-crypt w/ LUKS, a master key is wrapped with a derived key, which is derived 
from a passphrase using PBKDF2. While this tool is for block level devices, its handling of 
metadata (the good and the bad) influences our design of fscrypt’s metadata management. 


ecryptfs-utils 

https://wiki.archlinux.org/index.php/ECryptfs 

This is the tool for managing directories encrypted using eCryptfs. It provides many tools that 
address the common use cases for directory encryption (i.e. encrypting the home directory). As 
eCryptfs works via an overlay mount, creation of any encrypted directory requires root. Some of 
the eCryptfs tools use setuid binaries to get around this (we use an approach that avoids the 
need for a setuid binary in fscrypt). ecryptfs-utils also includes a PAM module (we will include 
something similar in fscrypt). 


e4crypt 

https://wiki.archlinux.org/index.php/ext4#Using file-based encryption 

This is the initial userspace tool that uses the ext4 filesystem encryption. It was a basic low-level 
tool and does not support many of the features we would want in a full-fledged system. fscrypt is 
intended to supersede e4crypt, see Alternatives considered for a longer discussion. 


Design 

fscrypt operates on two different types of keys: symmetric protector keys that are somehow 
obtained from the outside world and symmetric policy keys that are the actual key material 
passed to some part of the filesystem hierarchy. The diagram below shows how these 
components interact at a high level. 
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Filesystem: Policy Key 


Protectors and Protector Keys 

A Protector is an abstraction around a single method (or single secret) used to protect a 
directory. A Protector can check that a user has presented some desired secret, and then grant 
access to an encrypted directory accordingly. In practice, this means a Protector’s data, when 
combined with some outside secret information, should be enough to derive a specific 
symmetric key (called a Protector Key). Potentially, there is a very large number of ways to get 
this Protector Key. 





At least initially, we will focus on three main kinds of Protectors, but this design allows for 
expansion to other kinds of Protectors in later versions (e.g. a secret sealed by a TPM, on some 
U2E device, credentials stored in Active Directory, etc...). Our three Protector kinds are: 

1. A secret key derived from the user’s login passphrase (allowing for automatic unlocking) 

2. Asecret key derived from a custom passphrase (for removable media) 

3. Araw key passed via standard input (using a key from some Key Management Service) 


We will use a common interface to use different kinds of protectors. This is just an interface for 
using some external secret and getting a key (and returning an error if given the wrong secret). 


type SecretSource interface { 
GetProtectorKey(secret []byte) (key []byte, err error) 


} 


Other than the SecretSource, which contains all the data necessary to derive the Protector 
Key. Our Protectors will need to contain additional data as seen below. 


type Protector struct { 
ProtectorID []byte 
Name string 
Source SecretSource 


Here, the Name is a plain text label for the Protector, allowing easier management by the users 
of fscrypt. The Protector ID is an 8 byte identifier derived from the Protector Key. See Key 
Identifiers for specifically how this works. This ID will be used to throughout fscrypt to reference 
a Protector. It is important to note that the data for a Protector is stored in exactly one location. If 
another filesystem needs to use this Protector, it should reference the data, not copy it. 


Types of Protectors 


Our Source will have a differing structure depending on what kind of Protector we are dealing 
with. For Protector kinds (1) and (2), the secret from the outside world is some sort of 
memorized passphrase, (1) comes from login (i.e. PAM), and (2) comes from custom user input 
(i.e. a “Password: “ prompt). So for these two kinds, we use the Argon2id password hashing 
algorithm. Argon2id was the winning algorithm of the Password Hashing Competition and is a 
memory-hard hash function. It aims to reduce or eliminate the advantage specialized hardware 
has in brute-forcing password hashes. Argon2id uses a random Salt (see Random Data 
Generation) as well as costs for time, memory, and parallelism. These cost parameters should 
be specific to the system they are run on, and defaults will be pulled from a configuration file 
(see Global Defaults). Their structure is: 


type HashingCosts { 
Time int 
Memory int 
Parallelism int 


} 


where Time is the number of passes over memory, Memory is the amount of memory used, and 
Parallelism is the number of threads used. 


For Protector kind (1), we will use the login credentials for a specific user to protect the directory. 
Specifically, when a user creates this kind of Protector, they will have to enter their login 
passphrase. fscrypt will then check that this is actually their login passphrase. This is like 
/sbin/unix_chkpwd in that we can use PAM to make sure we have the correct password. This 
is done via a call to pam_authenticate. Note that this is separate from the PAM module. 


As these credentials may change at any time, we create a random long-term key (see Random 
Data Generation), which will then be wrapped with a key derived from their login passphrase. 
This allows us to maintain a consistent Protector key. See the diagram below: 
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So, our login Source will need the following data: 


type LoginPassphraseSource struct { 
Wid int 
Salt []byte 
HashingCosts 
WrappedKey 


} 


Exactly how our key wrapping works is discussed in Key Wrapping. As the key unwrapping is 
authenticated, if the unwrapping fails, we know the wrong passphrase has been provided. 


For Protector kind (2), we do almost the exact same thing as with kind (1), except that we don’t 
need the UID. We can just prompt for the custom passphrase. See the diagram below: 
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Passphrase 
So, our custom passphrase Source will need the following data 


type CustomPasswordSource struct { 
Salt []byte 
HashingCosts 
WrappedKey 


Similar to kind (1), this indirection allows us to change the custom passphrase without changing 
the Protector key. 


For Protector kind (3), where we use a raw key passed via standard input, we don’t need to use 
Argon2id. Passphrase hashes are only needed on passphrases. Instead we just will directly use 
the user key to unwrap some long term Protector key. See the diagram below: 






Unwrapped key 
Get Key from User | with derived key 


Right now this means that our Source in this case only needs a wrapped key. However, moving 
forward we might want the ability to use asymmetric cryptography to wrap this key being passed 
in. 

type RawKeySource struct { 


WrappedKey 
} 


Policies, Policy Keys, and fs/crypto 

While Protectors encapsulate a single protection mechanism for data, Policies encapsulate a 
single collection of directories which can be protected and unlocked as a single unit. A Policy is 
applied to some subset of the filesystem, and is protected by some set of Protectors. All files put 
into these directories are then encrypted. Then, if one of the Protectors is present, all the data in 
the directories is decrypted. 


The kernel interface for filesystem encryption, fs/crypto, supports using a designated key in 
the kernel keyring to encrypt a hierarchy of files and directories. Specifically, a designated key is 
applied to a specific empty directory, and then all files and directories (and files in those 
directories, etc...) are encrypted with keys derived from this designated key. For each Policy we 
have an associated key called a Policy Key. This key is randomly generated (see Random Data 
Generation) at Policy creation time and is the actual key material passed to the fs/crypto 
interface. This Policy/Policy Key is fixed for the lifetime of the directory. A diagram of this 
structure between Protectors, Policies, and directories is shown below. 





Our Policy structures will need to contain all the necessary data to get and apply a Policy Key, 
given that they have access to a Protector. This means we need the following structure: 


type Policy struct { 
PolicyID [ ]|byte 
EncryptionOptions map[string]string 
WrappedPolicyKeys [ ]WrappedPolicyKey 


} 


type WrappedPolicyKey struct { 
ProtectorID []byte 
WrappedKey 


The PolicyID is derived from the Policy Key as described in Key Identifiers. This ID will be 
used to throughout fscrypt to reference a Policy. The EncryptionOptions are the specific 
encryption modes to be used with this policy. The algorithms specified here can affect the length 
of the Policy Key, so they need to be included in a Policy’s Data (see TODO fix link for more 
information). 


Finally, we store the Policy Key wrapped with the various Protectors that are protecting this 
Policy. These WrappedPolicyKeys hold both the wrapped Policy Key as well as the 
Protector1D of the corresponding Protector. 


In fscrypt, while the Policy Keys are the actual cryptographic material passed to encrypt and 
decrypt the files, we often need a reliable way to refer to them both in fscrypt and though the 
fs/crypto interface. We do this via a function H( key), which given a key of any length, gives 
an 8 byte identifier for that key (see Key Identifiers for a description of H). This is how we get 
PolicyID. This identifier (also sometimes called a key descriptor), is what is passed through the 
fs/crypto kernel interface to set up encryption for a directory. To actually put stuff in an 
encrypted directory, the full Policy Key and PolicyID must be inserted into the kernel keyring. 
See Keyring Specifics for exactly how we do this. 


Keyring Specifics 
The Linux keyring facilities are significantly more complex than “just put a key in the keyring’. 
There are a few specifics about how fscrypt will interact with the kernel keyring. 

e The key is placed in a keyring accessible to the user. The exact specifics of our 
keyring strategy will depend on the specifics of the system. See Keyring Strategies for a 
more detailed comparison of the strategies and their corresponding requirements. 

e The key will have type logon. The main alternative considered here would be for the 
key to have type user. These behave in almost the exact same way, except that logon 
keys cannot be read from userspace once placed in the keyring. As these keys should 
only be read by the underlying filesystems anyway (as of right now, having type logon is 
a requirement of those filesystems), there is no loss of functionality by making them 
logon, and this also ensures greater security of the key material. 


e The keys will have default access for the user of fscrypt. Like the first point, this is 
necessary so the user doesn't need elevated privileges to insert a key. They key cannot 
be read anyway, and if the user starts messing around with keyctl, that’s their own 
problem. 

e The full description for a key in the keyring will be fscrypt:<PolicyID>. This 
makes sure our keys are not mixed up with other logon keys. Also, fs/crypto currently 
expects some additional information in the key description. e4crypt uses 
ext4:<key_id>. 


Keyring Strategies 


Session Keyring (Rejected) 


This strategy involves placing all keys for fscrypt in KEY_SPEC_SESSION_KEYRING. Using the 
current session keyring means that fscrypt will not need elevated privileges to place keys in this 
keyring, eliminating the need for a setuid binary. It also means that if something like 

pam _keyinit is used, the keys will be inherited across things like sudo. 


However, this strategy has a few significant downsides that led to it not being used. The first 
issue is that keys unlocked in one session for a user are (Sometimes) not accessible to the user 
in other sessions. This can create confusion for users unable to access certain directories. 
However, the bigger problem is that systemd is incompatible with use of the system keyring. The 
systemd maintainers are of the reasonable position that the session keyring just shouldn’t be 
used. 


User Keyrings (Version 0) 


To maintain compatibility with systemd, our next strategy is to place all keys for fscrypt in 
KEY_SPEC_USER_KEYRING. This means that all user sessions and systemd jobs will maintain 
access to fscrypt’s keys. Also, if pam_keyinit is in use, this means keys will still be maintained 
across sudo. 


However, there is the issue that root does not automatically possess the user keyrings for other 
users (and will get “permission denied” when it tries to access them). This is not really a security 
mechanism (as root can just drop privileges to any user) but a quirk in the keyrings userspace 
API. To fix this issue, whenever we drop privileges (in the PAM module or managing keys as 
another user), we also link the unprivileged user’s keyring into root’s user keyring. 


We end up getting a keyrings structure that looks like: 


User Session Keyring 

675528911 --alswrv 416424 65534 keyring: _uid_ses.416424 

1032520994 --alswrv 416424 65534 \_ keyring: _uid.416424 

154601706 --alsw-v 416424 5000 \_ logon: fscrypt:aa@3949c6cade18c 


Root Session Keyring 


158556543 --alswrv @ 65534 keyring: _uid_ses.@ 

1017858781 --alswrv @ 65534 \_ keyring: _uid.@ 

842387625 --alsw-v 2) ð \_ logon: ext4:7861415faea9380c 
1032529994 ---lswrv 416424 65534 \_ keyring: _uid.416424 

154601706 --alsw-v 416424 5000 \_ logon: ext4:aa@3949c6cade18c 
1021196992 --alswrv 121 65534 \_ keyring: _uid.121 

747845894 --alsw-v 121 5000 \_ logon: ext4:8ca028dab13ac4e4 


There are two potential issues with this strategy. The first issue happens if a user is not using 
the PAM module and never manages any keys as root, by running a command like: 

sudo fscrypt keyinit --keyring-user=joe 

sudo fscrypt unlock "/mnt/foo" --keyring-user=joe 


root may not be able to access the user’s keyring (as root permissions are necessary to setup 
the link). 


The second issue is that a folder that is shared (via unix permissions) between multiple users 
cannot be unlocked by one user and then accessed by another. This issue is impossible to 
avoid, due to a bug with the keyrings permission system. The bug is that keys/keyrings with 
“search” permissions (need for use with filesystem encryption) can be invalidated (immediately 
removed from the system). This means it is impossible to share a key with another user without 
exposing the first user to a Denial of Service attack. 


fscrypt Keyring (Version 1) 


As mentioned above, the concept of encrypting/decrypting files should be orthogonal to the 
concept of unix filesystem permissions. However, with the above strategy, the concepts are 
overlapping. However, after the keyrings bug is fixed, we will be able to separate these concepts 
by having a single fscrypt keyring, by having most of the keys in this keyring be read-only. 


This will be done by having a single fscrypt keyring owned by root, with several sub keyrings 
owned by each user (this is necessary to prevent a denial of service). This common keyring will 
then be linked into every user keyring, so that every user will be able to use all the keys. 


This gives the following keyring structure: 


Fscrypt Keyring 


180818635 ----s--v 2) @ keyring: fscrypt 

294171918 ----s--v 2) ð \_ keyring: fscrypt.@ 

842387625 ----s--v 2) (2) \_ logon: ext4:7861415faea9380c 

917260007 ----s--v 416424 5000 \_ keyring: fscrypt.416424 

154601706 ----s--v 416424 5000 \_ logon: ext4:aa@3949c6cade18c 
1490218 ----s--v 121 50009 \_ keyring: fscrypt.121 

747845894 ----s--v 121 5000 \_ logon: ext4:8ca@28dab13ac4e4 


User Session Keyring 
675528911 --alswrv 416424 65534 keyring: _uid_ses.416424 
1032520994 --alswrv 416424 65534 \_ keyring: _uid.416424 
180818635 ----s--v 2) (2) \_ keyring: fscrypt 
\ 


Root Session Keyring 


158556543 --alswrv @ 65534 keyring: _uid_ses.@ 
1017858781 --alswrv @ 65534 \_ keyring: _uid.@ 
180818635 ----s--v 2) (2) \_ keyring: fscrypt 


\ 


where the _uid_ses keyring could be an anonymous ses keyring. 


The main drawback of this strategy is that it requires root to configure all of the fscrypt 
keyrings and their permissions. This could be done on-demand in the PAM module, so we will 
probably just make using the PAM module or running sudo fscrypt keyint on login a hard 
requirement if we go this route. 


Filesystem keys (Version 2) 


The best solution to the keyring problem would be avoiding its use (and associated problems) 
entirely. A patch that would help with this has been proposed and was included in the mainline 
kernel (since 5.4). It adds a v2 of the fscrypt policy and caches the appropriate cryptographic 
transformations. 


It would be fairly straightforward to introduce further ioctls which directly add and remove entries 
from this cache without even using the keyring. This means keys would be provisioned directly 
to a filesystem (not globally) and could later be revoked by removing them and clearing the 
appropriate caches. 


The main drawback of this strategy is that it requires significant kernel changes that are unlikely 
to be backported (unlike the keyrings security bug described above). So we would need to 
continue supporting one of the above strategies for older kernels. 


Key Identifiers 
We compute the PolicyID from a Policy Key (and ProtectorID from a Protector Key) using a 
function H which is the first 8 bytes of a double application of SHA512. Specifically, 


func H(key []byte) (id [8]byte) { 


return sha512.Sum512(sha512.Sum512(key))[:8] 
} 


PolicyID = H(key) 


This, construction might seem a bit strange, but there are two good reasons for it. First, we don’t 
just use the first 8 bytes of a single application of some hash because some of the underlying 
crypto methods use the hash of the input key for cryptographic operations, and we don’t want to 
leak any important data through the key identifier. Second, this is the way the identifiers are 
implemented in e4crypt. Transitioning from e4crypt will be hard enough without a change to the 
identifier derivation algorithm. This choice should also allow directories encrypted with e4crypt 
to be used with fscrypt. 


Filesystem Requirements 
We attempted to make the requirements for the filesystems that work with fscrypt as minimal as 
possible, so that adding additional filesystems is easier and the filesystem-specific code is 
minimized. The requirements are as follows: 
1. Given a mount point for a filesystem, have a way to enable encryption on that filesystem. 
This may require root privileges (e.g. native ext4 encryption with tune2fs -O encrypt). 
2. Given an PolicyID and a path to an empty directory, the filesystem applies a policy to 
that directory so that any future contents of that directory will be encrypted with the 
corresponding Policy Key. Also, reading/writing to the directory is possible if and only if 
the corresponding key is in the keyring. 
3. Given a path to an encrypted directory, the filesystem returns the PolicyID of the Policy 
applied to that directory. 


Note that requirements (2) and (3) are met by implementing the fs/crypto interface. 
Specifically, any encrypting filesystem must support the following interface: 


type Options map[string]string 

type EncryptingFilesystem interface { 
// Enables encryption on this filesystem 
SetupEncryption(mountPoint string) error 
// Applying and querying an encryption policy for a directory 
SetPolicy(path string, policy_id []byte) error 
GetPolicy(path string) (policy_id []byte, err error) 


Key Wrapping 

In our discussion of both Policies and Protectors, we use wrapped keys to make access to a 
specific key (the SecretKey) only possible if another specific key (the WrappingKey) is present. 
For example, in our discussion of Login Protectors, our WrappingKey was the key derived from 


the user’s passphrase, and the SecretKey is the long-term key associated with that user. Also, 
in our discussion of Policies, our WrappingKey was the corresponding Protector Key, and the 
SecretKey is the Policy Key. 


When wrapping keys, we use AES256-CTR to encrypt our SecretKey with a WrappingKey. We 
also include a SHA256-based HMAC of the encrypted SecretKey and the IV, so that our 
encryption is authenticated. This is often referred to as “Encrypt then MAC”. Each wrapped key 
also gets its own randomly generated 16 byte IV. This gives the following structure for a 
WrappedKey: 


type WrappedKey struct { 
Iv []byte 
EncryptedKey []byte 
HMAC [ ]byte 


This way, if a user wishes to get the SecretKey, they must have the corresponding 
WrappingKey (and the WrappedKey data). Note that we will not directly use the WrappingKey as 
the encryption key and the HMAC key. We use unsalted SHA256-HKDF to derive two 
independent keys. We use AES in CTR mode, which brings along two potential objections: that 
the encrypted data is not authenticated and that we are at risk from repeated use of IVs. 


We opt for SHA256 for the HMAC and HKDF, even though SHA512/256 is often faster on 64-bit 
systems, because the SHA256 setup is simpler and often has better hardware support. 


For the first objection, we note in the Threat Model that some authentication is out of scope for 
this project (fscrypt cannot be used to verify the authenticity of the fscrypt binary); however, 
adding in an HMAC gives us two useful properties. First, if the WrappedKey is modified and an 
unwrap is attempted with the WrappingKey, the unwrap will fail. This allows us to detect 
malicious or accidental corruption of the metadata. Second, if the WrappedKey isn’t modified, the 
unwrap will fail unless we have provided the correct WrappingKey. This allows us to check that 
the correct key has been given (or password entered). 


For the second objection, CTR mode becomes broken if the same IV/Wrapping Key pair is used 
on two different plaintexts. Specifically, the XOR of the ciphertexts will be the XOR of the 
plaintexts. However, we avoid this problem as we use a random 128-bit IV for each wrapped 
key. This means on the order of 264 wrapped keys would need to be generated with the same 
WrappingKey before we would see a collision. Even if an attacker had the resources to 
generate such an obscene number of collisions, they would need the WrappingKey to do so (in 
which case the SecretKey could just be unwrapped directly). See Random Data Generation for 
how we handle getting random bytes in fscrypt. 


Random Data Generation 
Numerous security vulnerabilities have been caused by insufficient randomness in generating 
cryptographic keys. To prevent such problems in fscrypt, we will always generate our random 


data via the getrandom() system call (with GRND_NONBLOCK set and GRND_RANDOM not 
set). This way we will fail in cases where insufficient entropy is present and will avoid blocking. 


Metadata Storage 

Now that we have established the concepts of Policies and Protectors, fscrypt will need a way to 
store and manage this metadata. Other than the encrypted directories themselves, this is the 
only state that should persist between fscrypt operations. We need certain access control 
properties for storing the metadata, and a have a few different ways we could implement them; 
both are discussed below. 


Metadata Requirements 
There are a few properties that we want our metadata storage to have. 

e Fora filesystem that is set up for encryption, a user can create an encrypted directory 
(and its associated metadata) without being root. 

e Any user with access to an encrypted directory (via standard UNIX permissions) and the 
correct credentials can unlock the directory, regardless of who set up the directory. 

e Anon-root user cannot delete another user’s metadata, which would make the files 
corresponding to that metadata unreadable (see above Threat Model). 

e Anencrypted directory can be protected with a Protector whose data is on another 
filesystem. This is necessary to protect a folder on a USB drive with a user’s login 
password, for example. 

We do NOT require that any user be able to set up encryption on a filesystem, as this involves 
making privileged changes to the system. 


Metadata Storage Options 

Actually implementing the above requirements requires some careful thought. We need the 
corresponding metadata to be stored with the filesystem (so that the data is not lost if the 
filesystem media changes systems), yet we also need to prevent users from deleting another 
user’s metadata (which would effectively delete all their files). We considered the following 
solutions, and it seems root directory approach would be preferred. 


Using /.fscrypt directories with the sticky bit (current implementation) 


For this approach, we have /.fscrypt store the metadata for each filesystem. This means for 
each mounted filesystem, we will be able to find the metadata in the <mount point>/.fscrypt 
directory. In this directory, there would be two subdirectories policies and protectors. In the 
/.fscrypt/protectors directory there would be files where each name is the ProtectorID 
and the contents of the file is the serialized contents of the Protector. Similarly, the 
/.fscrypt/policies directory would have files where each name is the PolicyID and the 
contents of the file are the serialized contents of the Policies. See Metadata On-disk Format for 
what the contents of these files would look like. 


To prevent malicious deletion of metadata, the directory will be owned by root, only writable by 
root, but readable to everyone (aka 755 permissions). The policies and protectors 


directories would also be owned by root, but would be readable and writable to everyone and 
would have the sticky bit set (aka 1777 permissions the same as /tmp). Each created policy or 
protector file would be owned by the user creating them, readable to everyone, but only writable 
by that user (aka 644 permissions). 


These permissions require root to set up, but after the directories have been created, any user 
can create metadata which they can write to or delete. This also prevents other users from 
deleting each other's metadata due to the sticky bit being set on the policies and protectors 
directories. Note that this is just a protection from other users, and it does nothing to protect the 
metadata against physical access (see Threat Model). 


Pros: 

e Does not require kernel changes and can be implemented with existing filesystem 
encryption kernel interface. This also means that future and existing filesystems need to 
support a smaller set of common functionality. 

e The simple storage of Policies and Protectors makes the process more transparent to 
the user. The consistent metadata location makes using encryption with external media 
much easier. 

e Uses filesystem for organization and reads/writes, so we don’t have to separately 
implement this functionality. In the more common case where we only need to read the 
metadata, the user can directly read the file, no talking to the kernel, no talking to a 
setuid binary. 

e Writes new metadata as the user, allowing for Disk Quotas and other user-based 
controls and restrictions to work normally. 

e There is no code that deals with privilege elevation, either kernel code called from 
userspace, or a setuid binary that can be called by non-root users. This increases 
security and reduces the attack surface. 

Cons: 

e The files are visible to users, so all users can see how frequently a given Protector is 
used for various Wrappers. This isn’t that big of a deal as the metadata only contains 
instructions for getting the ProtectorKey and PolicyKey, not anything about the actual 
files it protects. 

e As these are just files owned by root, the root user can just delete them without a check 
for the invariant. The root user can also just delete the entire filesystem, but it might be 
unclear that deleting the /.fscrypt directory will cause data loss. 

e The individual data files are owned by their respective users, so these users could delete 
their own data in the /.fscrypt directory. 


Using a ~/.fscrypt folder 


This proposal is almost identical to the above one, except that instead of one global store of 
Policies and Protectors. Each user has their own store in a ~/.fscrypt directory. This store 
would be owned by the user, so the management of the store is simplified. The pros and cons 
are similar to the above proposal with the following exceptions: 


Pros: 


Cons: 


A metadata for a given user is stored in a single location. No need for sticky bit 
directories. 


As stores of metadata are now per-user as opposed to per-filesystem, the case for 
external media becomes more complex. Either a proposal like the one above needs to 
be done for external media, or we won't be able to access the encrypted files when the 
media is moved to another system. 

As the files would be owned by the user, they could just inadvertantly delete their 
~/.scrypt directory. We presume that regular users are more likely than the system 
administrator to do this and inadvertently cause data loss. 

Avery common potential use case for filesystem encryption is to encrypt the user’s 
entire home directory. This approach makes that impossible as the metadata is in the 
user’s directory. We could try to set up a different directory to store this stuff in (like 
/var/fscrypt), but then if Alice hasn't created /var/fscrypt/alice/ yet, Bob can 
create this directory and deny Alice the ability to store any metadata. 


Using special kernel functionality 


This proposal attempts to avoid any filesystem or setuid issues by simply moving the process of 
verifying and managing the metadata into the kernel. We would add in an ioctl to read or write 
the metadata that could be called by any user. In the case of writing, the kernel would then 
check that the appropriate keys were presented and then allow modification of the metadata. 
Also, the process of unwrapping the key and passing it to the keyring would be done in the 
kernel. The PolicyKey would never enter userspace. 


Pros: 
(J 


Cons: 


We no longer have to deal with any of the above filesystem-related issues as the 
metadata storage no longer uses a regular file. Inadvertent deletion is now impossible. 
The PolicyKeys never enter userspace, protecting them against potential compromise. 


This would require a significant kernel change, so we would have to coordinate between 
the kernel modifications and the fscrypt program. We would also introduce compatibility 
concerns, as fscrypt would not work with older kernels. 

Implementing this functionality in the kernel would be more difficult and complex than 
implementing it in userspace. 

A bug in our code potentially allows for an attacker to run code as the kernel. Compare 
this to the above solutions where a bug would just allow an attacker user-level privileges. 
In order for this kernel functionality to work, the underlying filesystem would need to give 
some hidden storage for all of this metadata. This means separate changes would need 
to be made to each filesystem that wants to work with fscrypt. 


Metadata On-disk Format 


The Policy and Protector structures discussed above will need to have some sort of on-disk 
representation. Each format has complexity, usability, and security tradeoffs; however, based on 
the analysis below, using Protocol Buffers would be the best bet. 


Protocol Buffers (current implementation) 


Protocol Buffers are cross-language binary serialization mechanism. Their focus is on efficiency 
(small size) and extensibility while keeping forward and backward compatibility. 
Pros: 

e Our metadata structures would be extensible. We could add/remove fields and still 
maintain backwards and forwards compatibility. This is important in the case of 
removable media, where the version on fscrypt that created the metadata might not be 
the version that reads it. 

e Protobuffs have interfaces to C, Go, Java, C++, Python, C# which can read the data 
directly into structures, making the programming easier and making the code work 
cross-platform easier. 

e The compact size of the binary representation reduces the overall size of the metadata. 

e Using a library that is well tested in industry reduces the risks for bug or security issues. 

Cons: 

e This requires the protocol buffer compiler to be a build dependency (under BSD license 
so no issues there) potentially increasing complexity. 

e The metadata is not human-readable. Protocol buffers also support a textual output 
mode, but that eliminates the benefit of their small size. 

e For languages other than the above languages, a good protobuf library might not exist. 


JSON, or other human-readable format 


Pros: 
e The metadata can now be read just by opening the file. This makes it easier to see the 
structure of the metadata (name a protector, which algorithm we are using, etc...). 
e The JSON format would allow us to add new values to the structure fairly easily. While 
not as extensible as protocol buffers, this might be all we really need. 
e JSON parsers are extremely widespread and available in almost all languages. 
e Using a library that is well tested in industry reduces the risks for bug or security issues. 
Cons: 
e The size of JSON is larger compared to protocol buffers 
e We will need a source dependency on whatever JSON parsing library we end up using. 


Rolling Our Own 


This approach would have fscrypt avoid a dependency by just manually specifying how the 
metadata is serialized. 
Pros: 

e Avoids an external dependency. 


e As we would have a custom serialization, we could make the sizes of the metadata quite 
compact. 
Cons: 
e Wouldn’t work well with other languages or if we wanted to change the structure of our 
metadata. Extensibility becomes quite difficult. 
Rolling our own serialization runs the risk of introducing bugs or security vulnerabilities. 
e Having a custom serialization will increase the code complexity. 


Configuration Files 

When creating new protectors or setting up new encrypted directories, we will often need to 
specify a considerable number of options (the kind of protector, the hashing parameters, the 
algorithm for filename encryption, etc...). To avoid undue burden on the user, we use 
configuration files. Some of these defaults make sense as global defaults and some make 
sense as per-filesystem defaults. We handle these cases separately. 


Global Defaults 

Our global defaults are used to set values for the Protector metadata if they are not specified by 
the user. This would include the default Source for a Protector and the corresponding costs 
(TCost, MCost, PCost) for the hashing algorithms. We will store this file at /etc/fscrypt.conf. 


While this configuration file can be edited by the system administrator, fscrypt can generate 
reasonable initial files based on the specifics of the system. The Source is left blank (users or 
the distribution would have to specify a default source). To determine our cost parameters, 
fscrypt runs many iterations of Argon2id to determine the optimal parameters to make the 
password hashing as hard a possible and take about one second on the system (different time 
targets may also be specified). 


Filesystem Default Options 

As discussed in Filesystem Requirements, when setting up encryption for a directory, we need 
to specify a list of options (this is the SetPolicy method in Filesystem Requirements). These 
options indicate our filename encryption algorithm, our content encryption algorithm, our 
version, and other flags. In the vast majority of cases, these options will not change on a given 
system. Thus, we will store this information /etc/fscrypt.conf. Then, we can automatically 
get our options when setting up an encrypted directory. See Command Line Interface to see 
how a user can override these defaults. An full /etc/fscrypt.conf might look like: 


{ 
"source": "“custom_passphrase", 
"hash_costs": { 
timen: <13, 
"memory": "2798452", 
"parallelism": "12" 
Jo 
"compatibility": "legacy", 
“options” =) { 


padding: 932"; 
HeEOntents +» TAES 256 X1S. , 
"filenames": "AES 256 CTS" 


i 
Here legacy is just a flag for supporting older kernels. Other flags could be added or removed 
as necessary. Note that the options data is also stored directly in the policy metadata. This is 
so if /etc/fscrypt.conf changes we do not lose access to our data. 





Config Flle Format 

As these configuration files will be read and written by both programs and human users, we 
have many choices as to which format to use. We could use the profile library in e2fsprogs (this 
is a small, simple library syntactically similar to TOML and used in krb5.conf, mke2fs.conf, 
and e2fsck.conf). We might also consider just using regular TOML, JSON (for better library 
support), or Protocol Buffers in textual mode (to avoid taking multiple dependencies). 


The current implementation of fscrypt uses JSON for the global config file. This is primarily due 
to it’s wide library support and its integration with Protocol Buffers. However, changing to any of 
the other formats would be a minor change. 


We opted not to use the textual mode of protocol buffers primarily because of its obscurity. 
JSON is more commonly used and more developed libraries. We also have to give up certain 
compatibility guarantees with textual protobufs. The main thing going for textual protobufs is that 
you can add comments, but this is even more obscure. 


Auto-unlocking Directories with PAM 
In Protectors and Protector Keys, we discussed a kind of Protector which used the user’s login 
password to automatically unlock directories (specifically where Source was pam). To do this we 


use Linux’s Pluggable Authentication Modules (PAM). This is a modular framework that allows 
us to hook into the system authentication system. To hook into these systems, we will need to 
write a PAM module, which will respond to various authentication related events. Specifically, 
our PAM module needs to deal with the following events: 

e When the user logs in, the pam_sm_authenticate() method in our PAM module will be 
called. This method will then pass the login password to the appropriate Protector. The 
pkey we get will then unwrap the corresponding hkeys placing them in the keyring, 
unlocking our directories. Here’s how ecryptfs handles it. 

e When the user changes their password, the pam_sm_chauthtok() method in our PAM 
module will be called. Then, we can use the old and new passphrases to unlock the old 
login Protector and create a new login Protector. We then rewrap all the hkeys with the 


new pkey from the new protector. Here’s how that’s done in ecryptfs. 


Example Actions 

Below are some schematics demonstrating how the config files, metadata objects, passphrases, 
derived keys, master keys, and filesystems all interact for some common operations. For all of 
these examples, lm assuming we are dealing with a single Protector whose source is 
stdin_password (i.e. the user just types in a password on the command line and we use 
Argon2id to derive the appropriate pkey) and a single Wrapper. 


Creating Initial fscrypt. conf 


In this example, we haven't run fscrypt yet, so we need to create the /etc/fscrypt. conf file 
for our system. The diagram below shows the process of creating this file. The primary 
challenge is finding the TCost, MCost, and PCost parameters that are correct for the system. 


: Num 
runtime.NumCPU() ber of Cores Available 


syscall.Sysinfo(). TotalRam Amount of RAM Available 
Time Target (default 1s) 
Default Source (optional) 


We use a heuristic to compute the optimal cost parameters for Argon2id. The basic idea is that 
we start with TCost = MCost = 1 and PCost as the number of CPUs. We then double MCost 
until we either are over the time target (then we are done) or we are using too much of the 
system’s RAM. In the latter case, we start doubling TCost until we hit the time target. 
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Argon2id, find the optimal 
hash parameters 


















Source 


Initial Fllesystem Setup 

Before we can use fscrypt on a given filesystem, we have to enable encryption on the 
filesystem, get the corresponding filesystem options, and set up the initial metadata directories 
and files. Note that enabling encryption on a filesystem can have significant ramifications. Most 
notably, the filesystem stops being compatible with older kernels that do not support encryption. 
For this reason, setting up the filesystem requires root privileges and will warn the user before 
mutating the filesystem. There are also many filesystems on which we can’t or shouldn't enable 
encryption (f2fs can’t have encryption turned on after the fact, block_size != PAGE_SIZE, kernel 
too old, etc...). In these cases, the setup fails and we inform the user on how they can fix their 
problem. 


In the example below, we show how a filesystem is set up for use with fscrypt. We don't yet 
encrypt any directories, generate any keys, etc ... 


Filesystem Mount Point Compatibility Target 


Enable encryption Defaultoption: Given the filesystem and 
on the filesystem compatibility target, get the 
appropriate filesystem options 





DefaultOptions 
Create /.fscrypt, 


/.fscrypt/policies, and 


/.fscrypt/protectors 
directories (owned by root, 
world readable) 





Getting the options is done with a call to the GetOptions() method, and enabling encryption on 
the file system is done with a call to the SetupEncryption() method (see Filesystem 
Requirements). Note that the options are passed both to the options. conf file and to our call 
to enable encryption. This is because some options are applied to the entire system, while some 
are just applied to a single encrypted directory. 


Creating a New Protector 

This example shows how we create a new protector. We are assuming that we are dealing with 
a passphrase based protector (kinds (1) or (2) in Protectors and pkeys); if we are using some 
other source, the functionality will be similar except we won't use Argon2id. We are also 
assuming that the fscrypt.conf file has already been created (see Creating Initial fscrypt.conf) 
and that we are using its defaults. Note that this only creates a protector, writes it to storage, 
and gives a pkey and pkey_id. No directories are set up for encryption (see Setting Up an 


Encrypted Directory). 









Source and 
Hash Costs 


H(pkey) 





Hash Costs 





Get pkey from 





Passphrase 


Get Passphrase using Argon2id 





Unwrapping a Protector 

This example shows how we unwrap the data in a Protector. Specifically, given a pkey_id and 
the corresponding password, we can get the pkey. Again, we are assuming that we are dealing 
with a passphrase-based Protector. This is just how a protector is unwrapped, see Unlocking an 
Encrypted Directory for how this works with decrypting directories. 
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Setting Up an Encrypted Directory 

In this example, we have some empty directory, and the user wishes to set up this directory for 
encryption protected with a custom password of their choosing. We are assuming that a new 
Protector will be created. If we wanted to use an existing protector (e.g. we want this directory 
unlocked automatically at login), this diagram would be almost the same except the protector 
would be unwrapped instead of created. encryption. We are also assuming that the 
corresponding filesystem has been set up for encryption (i.e. options . conf exists), and the 
user is using the default filesystem options and not specifying their own. 
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Unlocking an Encrypted Directory 

In this example, we have an encrypted directory (protected with some password) and we want 
to unlock it. This example shows the case of a single Wrapper/Protector protecting this directory. 
However, if there were multiple Protectors involved, we could choose which we wanted to use 
(i.e. which Wrapper to unwrap). 
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Unlock directory: 
Add key to session keyring 


Changing the Password 

In this example, we have an encrypted directory (protected with some password) and we want 

to change the password on it. By changing the password, we essentially change the Protector 

which is protecting the directory. Here, we are switch between two password-based Protectors; 
however, any change in Protectors would look quite similar. 


Get hkey_id from 
encrypted directory 


Wrap hkey with 
new EncKey 





Directory 












New 






Unwrap hkey 
with old EncKey 









pkey_id New 
WrappedKey 











Get New Get Old 
Passphrase Passphrase 





We have to be sure to delete the old Wrapper and old Protector after the password change. 


Program Structure 


fscrypt - Command Line Tool 

fscrypt is a command line tool that allows users to create and manage encrypted (with native 
filesystem encryption) directories. Most of fscrypt is devoted to determining the arguments to 
send down into libfscrypt. It does this by either by directly asking the user in an interactive 
session (the default), having the user provide various command line flags, or by assuming 
reasonable default arguments (quiet mode). This behavior is determined based on the 
command line flags passed into fscrypt. 


The primary goal of fscrypt is to make the common use cases quick and easy, while still allowing 
a user of fscrypt access to all of the functionality of libfscrypt. See Command Line Interface for 
more specifics about the types of commands in fscrypt. 


libfscrypt - Library 

libfscrypt is a library which implements the vast majority of the functionality of fscrypt. This 
library defines the concepts of Protectors and Policies. It allows users to add, delete, or modify 
these structures. It facilitates the creation of encrypted directory hierarchies and the 
management of key material. We have libfscrypt (as opposed to just having the functionality all 
together in fscrypt) to make it easier to have other interfaces into fscrypt (such as a GUI). 








Command Line Interface 


Main Commands 
These are the commands users will normally use to set up and modify encrypted directories. 


fscrypt unlock <target_directory> - gets the secret for some Protector from the 
user, unwraps the hkey, and unlocks the encrypted directory by adding the hkey to the 
session keyring. See Unlocking an Encrypted Directory for more details. 

fscrypt encrypt <target_directory> - Guides the user through an interactive 
process to create the appropriate Protectors and Policies depending on how they wish to 
protect the directory. See Setting Up an Encrypted Directory for more details. 

fscrypt status [<target_directory> | <mount_point>] - Prints out information 
for an encrypted directory, filesystem, or all of fscrypt. This is primarily information about 
the configuration files, Policies, and Protectors. 

fscrypt purge <mount_point> - Removes keys for the keyring and tries to lock the 
directory. This has many potential pitfalls, so it is experimental. 


Other Commands 
These lesser used commands are used for recovery and managing Protectors, Policies, and 
configuration files. 


fscrypt setup [--time <time_target>] - Initializes the global configuration file at 
/etc/fscrypt.conf. The bulk of this command’s functionality is finding the idea cost 
parameters so that Argon2id will run for about the target time. If not specified, the time 
target is 1 second. As the fscrypt.conf will be owned by root, this action requires root 
privileges. See Creating Initial fscrypt.conf for more information. 


e fscrypt setup <mount_point> - Initializes the metadata folders in 
<mount_point>/.fscrypt/. If the filesystem is owned by root, this action requires root 
privileges. See Initial Fllesystem Setup for more information. 

e fscrypt backup [create|restore] <mount_point> <backup file> - For the 
create subcommand, lets a user export all the cryptographic metadata at a specified 
mount point to a backup file. For the restore subcommand, the data in a backup file is 
used to restore the metadata at a specified mount point. 

e fscrypt recovery [create|restore] <directory> - For the create subcommand, 
a recovery key is created for a directory setup with fscrypt. This key will allow a user to 
regain access to the directory if they have forgotten their passphrase. This code is just 
an encoding of the appropriate underlying key. This is not a way to backup all of the 
metadata on a system. For that, use fscrypt backup. The restore subcommand uses 
a provided recovery key to unlock the directory. These recovery keys are based ona 
base-32 encoding of the Policy key. An example key looks like: 

CPXSHZ2IA-2ZT UA4BP-ORDVX6QI-CRFLUW50-KWMRFYWR-HY2V5E4E-YRHJMYSV-CBH20Z6W-5I 
G5617S-WKUVNDU2-30UGIX4U-O7KZ7DOZ-OWA7XNA= 

e fscrypt cleanup <mount_point> - Scans the specified filesystem, and removes any 
Policies that are not being used anywhere on that filesystem. This requires root. This 
function is needed because deleting an encrypted directory does not delete the 
corresponding Policy. However, it shouldn’t be run too frequently because it must 
traverse the entire filesystem. 

e fscrypt protector [add|delete|status] <pkey_id> - Fine grained management 
of Protectors. 

e fscrypt policy [add|delete|status] <pkey_id> <key_id> - Fine grained 
management of Policies. 


Potential Issues 


Locking Directories 

As of right now, there is no good way to implement an fscrypt lock function. This has to do 
with how the key material is handled by native filesystem encryption and the kernel keyring. The 
directories contents are unlocked when the correct hkey has been placed in the keyring. We 
might want to remove the key from the keyring and lose access to these directories. This can be 
done by revoking the key in the keyring; however, this process is isn’t guaranteed to remove 
cached data, so plaintext may still be visible even after revoking keys. The current solution is to 
make no guarantees about locking directories unless the filesystem is subsequently unmounted. 
When some of these issues are addressed in the kernel, we might be able to relax some of 
these limitations. 


Caching Issues 

Another problem with fscrypt (or any native filesystem encryption tool will face) revolves around 
caching of pages and key material. After the corresponding hkey has been placed in the kernel 
keyring, the per-file and per-directory keys are generated on-demand when a read or a write is 


issued to a file or directory. These derived keys and the pages they have decrypted are cached. 
This means that a user who does not have the correct hkey can still sometimes look at the 
encrypted directories and see plaintext contents. However, this isn’t much of a problem as unix 
file permissions can be used to prevent other logged-in users from seeing file contents. Again, 
filesystem encryption is not a replacement for unix file permissions. 


Releasing the tool 


There are two key places this tool could live once it is released. Based on the design constraints 
imposed by incorporating this project into util-linux, we think the best approach is to have fscrypt 
be a separate project mirrored into kernel.org/linux/utils. 


In util-linux 
On the mailing lists, it was mentioned that fscrypt (or something like it) would be added to 
util-linux. If we were to do this, it would be important to have consistency with the rest of that 
project, so that means: 
e The project will need to be written in C. We could not use a more safe language. 
e It will all need to be in a single file. We could maybe get away with two files (one for 
fscrypt and one for fscrypt-md). 
We would be very constrained in our dependencies (no serialization or profile libraries). 
Releasing versions of fscrypt would be tied to versions of util-linux. Coordination with the 
maintainers of that project would be very important. 
e Issues and patches would be managed through the standard linux mailing lists. 


As a Standalone Project (preferred) 

It might be better to take a similar to cryptsetup. Cryptsetup is the analogous tool for block 
devices, so an analogous approach makes sense. Cryptsetup is maintained in a separate 
repository (httos://gitlab.com/cryptsetup/cryptsetup/) where they manage issues and take pull 
requests. The cryptsetup project is also available at 
httos://www.kernel.org/pub/linux/utils/cryptsetup/ similar to util-linux which is also available in 
linux/utils/util-linux. 


We could something similar with fscrypt. It could be released as a project on Github (under 
Apache 2.0), and all the issues and pull requests could be managed there. We would then clone 
it into https://www.kernel.org/pub/linux/utils/. 


Having the project be standalone significantly increases our design flexibility. We can structure it 
how we like, use a safer language (like go), take dependencies, and release it when 
appropriate. Also, we would have a significantly better interface for managing bugs and pull 
requests. 


Future Ideas for Later Versions 


These are thoughts on future features that could be incorporated into fscrypt. 


Authenticity Guarantees (Secure Boot) - In the future, it might make sense to have 
fscrypt be part of some verified boot process. In this scenario, keys would be unlocked 
only after some boot-time checks had passed, preventing an attacker with physical 
access from compromising the system. System files could be encrypted with a system 
key and user files could be encrypted with user keys. While not currently part of fscrypt’'s 
threat model, with hardware support, it could be. If there was a way to verify the integrity 
of system data (e.g. with a TPM), we could verify the integrity of the fscrypt binary and 
fscrypt metadata before unlocking any keys. Depending on the hardware 
implementation, this might require the metadata or fscrypt binary to be placed in some 
sort of trusted storage. 

Encrypting Directories In-place - This would allow a user to call fscrypt encrypt on 
a non-empty directory. The existing data would then be encrypted as the directory was 
set up. To do this in a safe manner that doesn't require a large amount of additional 
space, we would need support from the underlying filesystems. 

Implementing fscrypt lock - This would allow a user to lock a directory and revoke 
the corresponding cryptographic keys. Right now this isn’t possible and would need 
support from the kernel to make it happen. See Locking Directories for more information 
about the difficulty involved. 

Introduce Asymmetric Key Wrapping - This would allow a user to protect a directory 
with a protector when they do not have the corresponding secret. This would allow Alice 
to share a directory with Bob, without Bob needing to do anything, and without Alice 
knowing Bob’s login passphrase. We opted not to use the functionality because it adds 
significant complexity without a compelling use case. 


Alternatives considered 


Write a tool specific to ext4 encryption, replace e4crypt. 

Going this route would probably get us to a working solution for ext4 a little faster, but it 
would contribute to the confusion and fragmentation when it comes to filesystem 
encryption utilities. 

Just use e4crypt. 

This isn’t a very good option because e4crypt does not support many features that we 
would want in a userspace tool to manage encryption. This includes changing a 
password, or storing any configuration information more than a single salt. The Ul is also 
less than desireable. 

Incorporate this functionality into cryptsetup 

Despite its general sounding name, cryptsetup only deals with dm-crypt. Adding 
filesystem operations to this tool seems outside the scope of cryptsetup. 


Document History 


2016-11-21 First draft for internal review 





2016-12-12 Second draft for external review 


